NumberCrunch II has the ability to execute code which has been written and compiled outside of the application with a Fortran, Pascal, C, or other compiler. These "external codes" (or xCODs) usually perform specialized numerical tasks like fourier transforms and matrix inversions. Many of these routines of this sort have been included with NCII; see the Library Routines folder.
If you have a good compiler and some programming experience on the Macintosh then you can write your own external codes and plug them into NCII. This file gives an overview of how to proceed and some background information about programming on the Mac.
Macintosh Resources
Macintosh applications are made up of a number of objects called "resources" in which exectable code, text, pictures, sounds, and a number of other kinds of data may be stored. Resources come in different types, each with a unique 4-letter indentifier. A few of the common types include
CODE the code that makes up an application, in <32k sized chunks,
TEXT ascii text,
PICT macintosh pictures, and
DLOG dialog templates.
NCII external code segments are also resources, with their own types:
xCOD NCII external code resource for the generic Mac version of NCII,
xCO2 NCII external code resource for the MC68881
math co-processer version of NCII, and
sCOD Text string describing the arguments to an xCOD or xCO2.
The easiest way to view and manipulate these resources is with a program called ResEdit, which is part of Apple's system software. Although ResEdit is not necessary for writing and installing NCII external code, it is very helpful for seeing which of these xCOD, xCO2, and sCOD resources are where, and for cutting, copying, and pasting them between files.
Each NCII routine consists of two resources: 1) the xCOD or xCO2 compiled code, and 2) the sCOD argument string. Both must have the same ID. Once the xCOD is written and compiled (which will be discussed in the next section), creating the sCOD (whose text is also described further down) and installing both into NCII can be done either with ResEdit or directly from NCII, with the Load xCOD command. If an sCOD is not found when the xCOD is loaded, NCII will ask for the string describing the arguments to the external code, and then create the sCOD itself.
If you choose to use ResEdit, here are a few tips.
• Create the sCOD by using the Create New Resource (cmd-K) command, and typing "sCOD" (case is important) in the dialog. The window which is created shows the resource in Hex and ascii; click at the right edge of the window to type or paste the ascii text for the sCOD.
• The IDs of the xCOD and sCOD resources are changed with the Get Resource Info (cmd-I) command. The two IDs must match.
• The names of the resources do not matter; the NCII routine's name is determined from the text in the sCOD.
Compiling the xCOD (or xCO2)
The details of how to compile the xCOD will, of course, depend on which compiler is used. Sample source code and associated files are included in this folder for Language Systems MPW FORTRAN and Symantec's THINK Pascal.
The compiler must be able to
• Create independent resources (sometimes called "drivers"), not just applications.
• Accept pointers to SANE (Standard Apple Numeric Environment) Extended numbers as procedure arguments. (Pointers are passed for all FORTRAN and Pascal "var" arguments.)
The xCOD may have up to 20 arguments, which may be
extended numbers,
arrays of extended,
or a pointer to another procedure.
Procedure pointers are difficult but possible to manage in Pascal; see the sample source files. In FORTRAN they are the norm.
For example, the source code for a short FORTRAN xCOD to add two numbers and return the result is
subroutine xADD(a,b, zOut)
extended a,b,zOut
zOut = a+b
return
end
while in Pascal the same routine would be
procedure xADD(var a,b, zOut:extended)
begin
zOut := a+b;
end;
More elaborate argument lists are given in the sample source files.
Each compiler uses a different mechanism for turning the source code into the desired xCOD resource. In the THINK Pascal environment a project file (.π) file manages the overall picture. The project type (Code Resource) and other parameters are set in dialogs. In MPW FORTRAN, a Script file MakeXCOD (MakeXCO2) tells the MPW (Mac Programmer's Workshop) how to compile and link the source code.
The sCOD Argument Description String
All that is left is to tell NCII how to use the xCOD.
The sCOD string used a Pascal-like procedure declaration, with lists of argument names followed by ": type" where "type" is one of the types given in the table in the section of the on-line help which explains xCOD's. A comment describing the xCOD usually follows the argument list. The argument types are:
declared type NCII passed object
real or extended real number, array, or n-array
number or num real or complex number, array, or n-array
RealArray real array or n-array
Complex complex number, array, or n-array
ComplexArray complex array or n-array
Array real or complex array or n-array
Prog or Program xCOD name or NCII user program
or Proc or Procedure
xCOD xCOD
With these types, an sCOD for either of the xADD procedures listed above might be
xCOD xADD(a, b, z: num), returns z=a+b
A more elaborate sCOD might be
xCOD xSAMPLE(n:num; x,y:array; prog theSubr(a,b:num) ), a sample xCOD
NCII procedures which are passed as arguments must always be of the form
prog TheProg(n:num; zIO:array)
where zIO[1…n] is an array with n components used for input/output.
Two other notes:
• NCII arguments which are undefined when passed to an xCOD are set to 0.0; therefore, they must be declared num, number, real, or extended.
• If an argument is declared complex or ComplexArray but isn't, then it is converted to complex before it is passed. The external code may deal with this array as it likes, it is just a long array of numbers packed (r1, i1, r2, i2, ...) where "r" is the real part and "i" is the imaginary.
Final Remarks
This whole procedure sounds much more complicated than it really is. However, it is true that xCOD's are fairly unforgiving. If, for example, you pass an array of 10 numbers to an external routine but then try to treat it as if it were an array with a size of 20, then your Mac will almost certainly crash. Also, there is no easy way to debug an xCOD once it is installed inside NCII; you should test it inside your own compiler's environment.
If you run into problems, feel free to drop me a line; I'll do what I can.
Also, if there is interest, I would be glad to collect xCOD's and their interface routines (like the ones in the Library Routines folder) and distribute them to other users.
